Skip to main content

Configure KYC&KYB Session TTL

Overview​

The Configure KYC & KYB Session TTL API allows you to set the default TTL (time-to-live) for KYC and KYB session tokens for a specific application. This endpoint stores the TTL value in seconds against the application, ensuring that subsequent KYC and KYB session token creation uses the configured duration.

Authentication​

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials. The application context is automatically determined from your authentication credentials, eliminating the need to specify an application ID in the request.

Required Headers​

  • X-API-KEY: Your server API key (required)
  • Content-Type: application/json

Endpoint​

TTL Configuration Context​

This TTL configuration applies to both:

  • KYC (Know Your Customer) session tokens for individual person verification workflows
  • KYB (Know Your Business) session tokens for company verification and onboarding workflows

The configured TTL value determines how long authentication tokens remain valid during the verification process, affecting both person and company application flows.

Request Body​


### Path Parameters

This endpoint does not require path parameters. The application context is determined from the authentication credentials.

## Request Body

### Interface Definitions

```ts
interface ConfigTTLRequest {
   ttlNumber: number;
}

interface ConfigTTLResponse {
   statusCode: number;
   data: {
      message: string;
   };
}

Request Example​

{
   "ttlNumber": 1800
}

Field Descriptions​

  • ttlNumber (required): Integer number of seconds that KYC and KYB session tokens should live
    • Minimum recommended: 60 (1 minute)
    • Typical values: 900 (15 minutes), 1800 (30 minutes), 3600 (1 hour)
    • Suggested bounds: minimum 300, maximum 86400 (24 hours)

Response Structure​

Success Response​

{
   "statusCode": 200,
   "data": {
      "message": "TTL configured successfully"
   }
}

Error Response​

{
   "statusCode": 400,
   "message": "Validation failed",
   "errors": [
      {
         "field": "ttlNumber",
         "message": "ttlNumber is required and must be an integer >= 60"
      }
   ]
}

Usage Guidelines​

TTL Recommendations by Use Case​

KYC (Person Verification)​

  • Quick Identity Verification: 900 seconds (15 minutes)
  • Standard KYC Process: 1800 seconds (30 minutes)
  • Complex Verification: 3600 seconds (1 hour)

KYB (Business Verification)​

  • Document Collection: 3600 seconds (1 hour)
  • Multi-step Company Onboarding: 7200 seconds (2 hours)
  • Complex Corporate Structure: 14400 seconds (4 hours)

Security Considerations​

  • Shorter TTL values provide better security but may impact user experience
  • Longer TTL values improve user experience but increase security risk if tokens are compromised
  • Consider your verification complexity when setting TTL values
  • KYB processes typically require longer TTL due to additional documentation and stakeholder involvement

Best Practices​

  • Set TTL based on your average completion time for verification processes
  • Monitor session timeout rates and adjust TTL accordingly
  • Use shorter TTL for high-risk applications
  • Consider different TTL values for different application types (KYC vs KYB)

Error Handling​

Common error scenarios and their resolutions:

Validation Errors​

  • TTL too short: Minimum recommended value is 300 seconds (5 minutes)
  • TTL too long: Maximum recommended value is 86400 seconds (24 hours)
  • Invalid format: TTL must be a positive integer

Implementation Example​

async function configureTTL(ttlSeconds) {
   try {
      const response = await fetch('/api/configttl', {
         method: 'PUT',
         headers: {
            'Content-Type': 'application/json',
            'X-API-KEY': 'your-api-key',
         },
         body: JSON.stringify({
            ttlNumber: ttlSeconds,
         }),
      });

      if (response.ok) {
         const result = await response.json();
         console.log('TTL configured successfully:', result.data.message);
         return result;
      } else {
         const errorData = await response.json();
         throw new Error(errorData.message || 'TTL configuration failed');
      }
   } catch (error) {
      console.error('TTL configuration error:', error);
      throw error;
   }
}

// Example usage
// For KYC processes (30 minutes)
await configureTTL(1800);

// For KYB processes (2 hours)
await configureTTL(7200);
TTL Optimization

Monitor your verification completion rates and adjust TTL values based on actual user behavior. Consider implementing different TTL values for different verification complexity levels.

Security Notice

Longer TTL values increase security risks. Balance user experience with security requirements when configuring session durations.

Application Context

TTL configuration is applied per application. Each application can have its own session duration settings for both KYC and KYB processes.